TECConvertTextToMultipleEncodings

Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 3 - Text Encoding Converter Reference / Text Encoding Converter Functions

TECConvertTextToMultipleEncodings
Converts text in the source encoding to runs of text in multiple destination encodings.
pascal OSStatus TECConvertTextToMultipleEncodings(
                     TECObjectRef encodingConverter, 
                     ConstTextPtr inputBuffer, 
                     ByteCount inputBufferLength, 
                     ByteCount *actualInputLength, 
                     TextPtr outputBuffer, 
                     ByteCount outputBufferLength, 
                     ByteCount *actualOutputLength, 
                     TextEncodingRun outEncodingsBuffer[], 
                     ItemCount maxOutEncodingRuns, 
                     ItemCount *actualOutEncodingRuns);
encodingConverter
The reference to the text encoding converter object to be used for the conversion. This is the reference returned by the function TECCreateOneToManyConverter (page 99).
inputBuffer
The stream of text to be converted.
inputBufferLength
The length in bytes of the stream of text specified in the inputBuffer parameter.
actualInputLength
A pointer to a value of type ByteCount. On output, this value is the number of source text bytes that TECConvertTextToMultipleEncodings converted.
outputBuffer
A pointer to a buffer for a byte stream. On output, this buffer holds the converted text.
outputBufferLength
The length in bytes of the buffer provided by the outputBuffer parameter.
actualOutputLength
A pointer to a value of type ByteCount. On output, this value is the number of bytes of the converted text returned in the buffer specified by the outputBuffer parameter.
outEncodingsBuffer[]
An array of text encoding runs for output. Note that the actual byte size of this buffer should be actualOutEncodingRuns * sizeof(TextEncodingRun). See TextEncodingRun (page 45) for more information about the TextEncodingRun structure.
maxOutEncodingRuns
The maximum number of runs that will fit in the outEncodingsBuffer array.
actualOutEncodingRuns
A pointer to a value of type ItemCount. On output actualOutEncodingRuns contains the number of runs put in outEncodingsBuffer array.
function result
A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) for a list of possible values. If the outEncodings buffer is filled while converting text, then function returns kTECOutputBufferFullStatus. If there is not enough memory available for TECConvertTextToMultipleEncodings to convert the text when allocating internal buffers, the function returns the appropriate Memory Manager result code.

DISCUSSION
The TECConvertTextToMultipleEncodings function converts the stream of text you pass it to runs of destination encodings specified in the converter object. The function relies on the specified converter object for the source encoding in which the text is expressed, the destination encodings, and the train of encodings forming the intermediate conversion path (if one is explicitly specified). The function returns the text in the output buffer that you provide.
In allocating an output buffer, a good rule of thumb is larger is better, basing your estimate on the byte requirements of the destination encoding. You should always allocate a buffer at least 32 bytes long. For the function to return successfully, the output buffer you allocate must be large enough to accommodate at least part of the converted text. Then, if the function cannot convert all of the text, it executes successfully, returns the portion of the text it converted, and returns the number of source bytes it removed from input in the actualInputLength parameter. You can use this number to identify the next byte to be taken and to determine how many bytes remain. To convert the remaining text, you simply call the function again with the remaining text and a new output buffer.
If the output buffer you allocate is too small to accommodate any of the converted text, the function fails. For example, if the destination encoding requires bytes in addition to the actual text (for instance, an escape sequence preceding the converted text), your buffer must be large enough to accommodate both.

IMPORTANT
If the destination encoding is a character encoding scheme--such as ISO-2022-JP, which begins in ASCII and switches to other coded character sets through limited combinations of escape sequences--then you need to allocate enough space to accommodate escape sequences that signal switches. ISO-2022-JP requires 3 to 5 bytes for an escape sequence preceding the 1-byte or 2-byte character it introduces. If you allocate a buffer that is less than 5 bytes, the TECConvertText function could fail, depending on the text being converted.
The Text Encoding Converter creates internal buffers for all multistaged (that is, indirect) conversions that hold intermediate results.

SEE ALSO
The function TECConvertText (page 95)